home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 037a / tpclone.zip / TPCLONE.DOC next >
Text File  |  1990-05-16  |  8KB  |  165 lines
  1. TPCLONE - Routines for cloning typed constants into a program
  2. -------------------------------------------------------------
  3. TurboPower Software
  4. 10/88
  5. Version 1.0
  6. Released to the public domain
  7.  
  8. Overview
  9. ------------------------------------------------------------------------------
  10. TPCLONE is designed to assist in the writing of installation programs:
  11. programs that configure other programs by modifying their contents. The key to
  12. writing such programs is to store all data that is to be modified in one or
  13. more typed constants, organized into a contiguous block or a single record
  14. structure, and to precede them with an ID string that can be located by the
  15. installation program.
  16.  
  17. Here's an example of what we mean:
  18.  
  19.   const
  20.     {--- ID string at the beginning of the block ---}
  21.     MyIdString : string[28] = 'My installation area follows';
  22.     {--- beginning of installation area ---}
  23.     MyInstallationOption1 : Byte = 1;
  24.     MyInstallationOption2 : Word = 2;
  25.     MyInstallationOption3 : LongInt = 3;
  26.     {--- end of installation area ---}
  27.  
  28. The installation program would have a corresponding block of typed constants
  29. or variables that matches the original exactly in terms of size, type, and
  30. number of constants:
  31.  
  32.   const
  33.     IdString : string[28] = 'My installation area follows';
  34.     InstallationOption1 : Byte = 1;
  35.     InstallationOption2 : Word = 2;
  36.     InstallationOption3 : LongInt = 3;
  37.  
  38. Using the facilities provided in TPCLONE, the installation program can then
  39. take the following steps: 1) locate the ID string in the target program's EXE
  40. file; 2) read the current contents of the installation area into its local
  41. copy; 3) allow the user to somehow modify or accept the current installation
  42. options; and then 4) write the modified contents of the installation area back
  43. to disk.
  44.  
  45. Using TPCLONE
  46. ------------------------------------------------------------------------------
  47. TPCLONE interfaces the types, variables, and routines described below. For an
  48. example of how to use them in a program, see TPKEYS.PAS.
  49.  
  50. type ClonePack =
  51.        record
  52.          CloneF : File;
  53.          CloneT : LongInt;
  54.        end;
  55.  
  56.   A ClonePack contains all information needed by TPCLONE about a file being
  57.   modified.
  58.  
  59. type  DateUpdateType = (UpdateNone, UpdateDate, UpdateAll);
  60. const DateUpdate : DateUpdateType = UpdateDate;
  61.  
  62.   DateUpdate affects the behavior of the CloseForCloning procedure. If it is
  63.   set to UpdateNone, the closed file will have the same date and time stamp
  64.   that it had when it was opened. If it is set to UpdateDate, the date of the
  65.   file will be changed, but not the time. (We prefer this option because, like
  66.   Borland, we use the time stamp as a version number: 05:00 am = version
  67.   5.00.) If it is set to UpdateAll, both the date and time of the file will be
  68.   updated normally.
  69.  
  70. var CloneError : Word;
  71.  
  72.   This variable, much like the DosError variable in the DOS unit, contains the
  73.   code for any I/O errors that occur in TPCLONE. After calling any of the
  74.   routines in the unit, you should therefore check CloneError to determine if
  75.   there was an error.
  76.  
  77. procedure OpenForCloning(FName : string; var CP : ClonePack);
  78.  
  79.   This routine opens the specified file for cloning. If the file cannot be
  80.   opened, CloneError will contain the error code. This routine must be called
  81.   either directly or indirectly (by InitForCloning) before any of the other
  82.   routines in the unit may be called.
  83.  
  84. function FindDefaultsEnd(var CP : ClonePack;
  85.                          var ID; IdSize : Word;
  86.                          Skip : LongInt) : LongInt;
  87.  
  88.   FindDefaultsEnd searches the file to be cloned, starting at the end of the
  89.   file and working backward, for the specified ID value. Normally ID is a
  90.   string, and IdSize is equal to SizeOf(IdString). If ID is found, its
  91.   offset in the clone file is returned as the function result. If it is not
  92.   found, the result will be 0, and CloneError will contain the I/O error code
  93.   if there was one. Skip is the number of bytes at the end of the file to be
  94.   skipped before starting the search.
  95.  
  96. function FindDefaultsStart(var CP : ClonePack;
  97.                            var ID; IdSize : Word;
  98.                            Skip : LongInt) : LongInt;
  99.  
  100.   FindDefaultsStart searches the file to be cloned, starting at the beginning
  101.   of the file and working forward, for the specified ID value. Normally ID is
  102.   a string, and IdSize is equal to SizeOf(IdString). If ID is found, its
  103.   offset in the clone file is returned as the function result. If it is not
  104.   found, the result will be 0, and CloneError will contain the I/O error code
  105.   if there was one. Skip is the number of bytes at the beginning of the file
  106.   to be skipped before starting the search.
  107.  
  108. function InitForCloning(FName : string; var CP : ClonePack;
  109.                         var ID; IdSize : Word) : LongInt;
  110.  
  111.   This routine simply calls OpenForCloning to open the clone file, and
  112.   FindDefaultsEnd to search for the ID. Normally ID is a string, and IdSize is
  113.   equal to SizeOf(IdString). If ID is found, its offset in the clone file is
  114.   returned as the function result. If it is not found, the result will be 0,
  115.   and CloneError will contain the I/O error code if there was one.
  116.  
  117. procedure LoadDefaults(var CP : ClonePack; FileOfs : LongInt; var Defaults; Bytes : Word);
  118.  
  119.   This routine moves the file pointer for the clone file to the specified
  120.   offset (FileOfs), and reads Bytes bytes of data into Defaults. CloneError
  121.   will contain the I/O error code if there was one, or 100 if the number of
  122.   bytes actually read in were less than the number requested.
  123.  
  124. procedure StoreDefaults(var CP : ClonePack; FileOfs : LongInt; var Defaults; Bytes : Word);
  125.  
  126.   This routine moves the file pointer for the clone file to the specified
  127.   offset (FileOfs), and writes Bytes bytes of data from Defaults to disk.
  128.   CloneError will contain the I/O error code if there was one, or 101 if the
  129.   number of bytes actually written were less than the number requested.
  130.  
  131. procedure CloseForCloning(var CP : ClonePack);
  132.  
  133.   This routine alters the date/time stamp for the clone file in the manner
  134.   specified by DateUpdate, then closes it. CloneError will contain the error
  135.   code if an I/O error occurs.
  136.  
  137. Warning
  138. ------------------------------------------------------------------------------
  139. Special precautions need to be taken when using the techniques we've been
  140. describing with Turbo Pascal 5.0. First, you need to insure that Turbo 5's
  141. word alignment option is off--{$A-}--at least in the program(s) or unit(s)
  142. containing the typed constants in question. Second, when declaring a block of
  143. typed constants, you should be sure that the word "const" does not appear
  144. anywhere in the middle of the block. The following declarations could cause
  145. problems, for example:
  146.  
  147.   const
  148.     IdString : string[17] = 'Installation area';
  149.   const
  150.     ConfigOption1 : Byte = 1;
  151.   const
  152.     FutureConfigOption : Byte = 0;
  153.   const
  154.     ConfigOption2 : Byte = 2;
  155.  
  156. Since "IdString" will probably never be used in the program to be installed,
  157. Turbo 5's linker (which "smart links" data as well as code) would not include
  158. it in the EXE file. Result: the installation program will fail when it tries
  159. to find it.
  160.  
  161. Assuming that FutureConfigOption is also unused, the smart linker would remove
  162. it as well. Result: when the block of typed constants is read in,
  163. ConfigOption2 would be read into the area where FutureConfigOption is supposed
  164. to be.
  165.